Development View
This page describes the most important parts for the software implementation of the DCM standards. For the full technical specification, please refer to the standard CX-0128 Demand and Capacity Management Data Exchange.
Introduction
This document provides developers with resources to accelerate the development of apps and services.
Capabilities of a DCM application
CX-0128 Demand and Capacity Management Data Exchange describes the following capabilities:
| Capability | Category | Related Aspect Models | Related APIs |
|---|---|---|---|
| Providing and consuming demand data | Core | WeekBasedMaterialDemand | WeekBasedMaterialDemand API |
| Providing and consuming capacity data | Core | WeekBasedCapacityGroup | WeekBasedCapacityGroup API |
| Comparing demand and capacity data | Core | WeekBasedMaterialDemand WeekBasedCapacityGroup | N/A |
| Demand volatility metrics | Outer Core | WeekBasedCapacityGroup | WeekBasedCapacityGroup API |
| Simulated delta production | Outer Core | WeekBasedCapacityGroup | WeekBasedCapacityGroup API |
| Load factors | Outer Core | WeekBasedCapacityGroup | WeekBasedCapacityGroup API |
| Digital twins | Extended | WeekBasedMaterialDemand WeekBasedCapacity Group | DCM Asset Administration Shell API |
| Request for update | Extended | IdBasedRequestForUpdate | IdBasedRequestForUpdate AP |
| Comments | Extended | IdBasedComment | IdBasedComment API |
| Supply chain disruption notifications | Extended | demandAndCapacityNotification | DemandAndCapacityNotification API |
- Core capabilities are mandatory within the standard.
- Outer core capabilities share APIs and aspect models with core capabilities, but are optional.
- Extended capabilities introduce aspect models or APIs beyond the core and are optional.
A MVP approach can be followed when developing software, implementing CX-0128, by taking care of core capabilities first, followed by outer core and finishing with extended capabilities.
Roles and rights of a DCM application
CX-0128 Demand and Capacity Management Data Exchange describes the business roles customer and supplier. In addition an admin role might be a sensible addition to any application. Most companies within a supply chain will have need of both business roles. Individual users within a company might need access to both business roles.
| Role | Capabilities |
|---|---|
| Customer | - Modify WeekBasedMaterialDemand - Compare WeekBasedMaterialDemand to WeekBasedCapacityGroup - Utilize comments - Utilize supply chain disruption notification |
| Supplier | - Modify WeekBasedCapacityGroup - Compare WeekBasedMaterialDemand to WeekBasedCapacityGroup - Link WeekBasedMaterialDemand to WeekBasedCapacityGroup - Utilize comments - Utilize supply chain disruption notification |
| Admin | - Configure Request for update |
Aspect models utilized by a DCM application
Application Programming Interfaces
APIs as data assets
The data consumer registers one data-asset per API with its own EDC. Those data-assets need a dataAddress with a baseURL pointing to the URI of the API endpoint. The same dataAddress needs to be setup to use the consumers EDC as a proxy, utilizing the different proxy related properties within the dataAddress object.
Asset example
{
"@id": "capacitygroup-prod",
"@type": "Asset",
"properties": {
"http://purl.org/dc/terms/type": {
"@id": "https://w3id.org/catenax/taxonomy#DcmWeekBasedCapacityGroup"
},
"https://w3id.org/catenax/ontology/common#version": "2.0",
"id": "capacitygroup-prod"
},
"dataAddress": {
"@type": "DataAddress",
"proxyPath": "false",
"oauth2:clientId": {{clientID}},
"oauth2:tokenUrl": {{tokenUrl}},
"type": "HttpData",
"proxyMethod": "true",
"oauth2:clientSecretKey": "dcm-api-client-secret",
"oauth2:scope": "roles",
"proxyQueryParams": "true",
"proxyBody": "true",
"baseUrl": "https://myDCMapp.mycompany.com/catx/apis/weekbasedcapacitygroup"
},
Data exchange
The data provider is required to use HTTP POST to call the API in order to transfer the data. The POST request has to contain a messageHeader and can contain multiple information objects, with information objects being the different aspect models. Because one API is dedicated to one aspect models mixing different aspect models into the same payload as information objects will result in a malformed payload.
Payload structure
{
"messageHeader":
<messageHeaderObject>,
"content":{
"informationObject":[
<informationObject>,
<informationObject>
]
}
}
This format ensures that the header, which contains metadata about the message, is kept separate from the content, which includes the actual data being exchanged. The content section can hold multiple informationObject entries. These objects can be one of the following types: WeekBasedMaterialDemand, WeekBasedCapacityGroup, IdBasedComment or IdBasedRequestForUpdate.
The master reference for generating additional file formats and serializations is the RDF turtle file, which is an instance of the Semantic Aspect Meta Model. The RDF turtle file for the messageHeaderObject is defined in a centralized shared aspect model and can be accessed at the following URL:
https://github.com/eclipse-tractusx/sldt-semantic-models/blob/main/io.catenax.shared.message_header/3.0.0/MessageHeaderAspect.ttl
Within the RDF turtle file, you will find detailed descriptions for how to use the message header.
For further information on the APIs and how to use them in order to facilitate data exchange, please refer to CX-0128 Demand and Capacity Management Data Exchange and CX-0018 Dataspace Connectivity
APIs utilized by a DCM application
- WeekBasedMaterialDemand API
- WeekBasedCapacityGroup API
- RequestForUpdate API
- IdBasedComment API
- DCM Asset Administration Shell API (AAS API)
Testing a DCM application
Having a well organized and documented testing of a DCM application is advantageous not only for the whole development process, but especially because test-runs can be used as proof for required certification of the application.
It is recommended to compartmentalize tests into test-sets from which different user journeys can be built, depending on which specific capabilities are supposed to be tested by the user journey. Below you will find tests, test-sets and user journeys. Please be aware that they do not provide full coverage of the standard and depending on how you build your application you will need to expand on them.
List of Test-Sets
| Test-Set | Description | Tests in test-set |
|---|---|---|
| Customer: Prepare yourself | Prepares customer for the user journey, by setting up EDC, data assets, wallet, certificates etc. | - Setup EDC - Register APIs as assets - Check wallet for certificates - Prepare variables for other tests - User journey specific preparation |
| Supplier: Prepare yourself | Prepares supplier for the user journey, by setting up EDC, data assets, wallet, certificates etc. | - Setup EDC - Register APIs as assets - Check wallet for certificates - Prepare variables for other tests - User journey specific preparation |
| Customer: Create WeekBasedMaterialDemand | Tests the implementation of the aspect model | - Create valid aspect model - Create invalid aspect model - Create user journey specific aspect model |
| Customer: Provide WeekBasedMaterialDemand | Tests communication via EDC | - Provide valid payload - Provide invalid payload - Provide user journey specific payload |
| Supplier: Consume WeekBasedMaterialDemand | Tests the implementation of the API and the aspect model | - Consume valid payload - Consume invalid payload - Consume user journey specific payload |
| Supplier: Create WeekBasedCapacityGroup | Tests the implementation of the aspect model | - Create valid aspect model - Create invalid aspect model - Create user journey specific aspect model |
| Supplier: Provide WeekBasedCapacityGroup | Tests communication via EDC | - Provide valid payload - Provide invalid payload - Provide user journey specific payload |
| Customer: Consume WeekBasedCapacityGroup | Tests the implementation of the API and the aspect model | - Consume valid payload - Consume invalid payload - Consume user journey specific payload |
| Customer: Visualize CapacityGroup together with MaterialDemand | Minor user acceptance test | - Bottleneck calculation - Surplus calculation - Zero deviation calculation - User journey specific calculation |
| Supplier: Visualize CapacityGroup together with MaterialDemand | Minor user acceptance test | - Bottleneck calculation - Surplus calculation - Zero deviation calculation - User journey specific calculation |
| Customer: Create IdBasedRequestForUpdate | Tests the implementation of the aspect model | - Create valid aspect model - Create invalid aspect model - Create user journey specific aspect model |
| Customer: Provide IdBasedRequestForUpdate | Tests communication via EDC | - Provide valid payload - Provide invalid payload - Provide user journey specific payload |
| Supplier: Consume IdBasedRequestForUpdate | Tests the implementation of the API and the aspect model | - Consume valid payload - Consume invalid payload - Consume user journey specific payload |
| Supplier: Create IdBasedRequestForUpdate | Tests the implementation of the aspect model | - Create valid aspect model - Create invalid aspect model - Create user journey specific aspect model |
| Supplier: Provide IdBasedRequestForUpdate | Tests communication via EDC | - Provide valid payload - Provide invalid payload - Provide user journey specific payload |
| Customer: Consume IdBasedRequestForUpdate | Tests the implementation of the API and the aspect model | - Consume valid payload - Consume invalid payload - Consume user journey specific payload |
| Customer: Create IdBasedComment | Tests the implementation of the aspect model | - Create valid aspect model - Create invalid aspect model - Create user journey specific aspect model |
| Customer: Provide IdBasedComment | Tests communication via EDC | - Provide valid payload - Provide invalid payload - Provide user journey specific payload |
| Supplier: Consume IdBasedComment | Tests the implementation of the API and the aspect model | - Consume valid payload - Consume invalid payload - Consume user journey specific payload |
| Supplier: Create IdBasedComment | Tests the implementation of the aspect model | - Create valid aspect model - Create invalid aspect model - Create user journey specific aspect model |
| Supplier: Provide IdBasedComment | Tests communication via EDC | - Provide valid payload - Provide invalid payload - Provide user journey specific payload |
| Customer: Consume IdBasedComment | Tests the implementation of the API and the aspect model | - Consume valid payload - Consume invalid payload - Consume user journey specific payload |
| Customer: Visualize IdBasedComment together with CapacityGroup and MaterialDemand | Minor user acceptance test | - Comment linked to WeekbasedCapacityGroup - Comment linked to WeekbasedMaterialGroup - Comment linked to IdBasedComment |
| Supplier: Visualize IdBasedComment together with CapacityGroup and MaterialDemand | Minor user acceptance test | - Comment linked to WeekbasedCapacityGroup - Comment linked to WeekbasedMaterialGroup - Comment linked to IdBasedComment |
List of User-Journeys
| # | User Journey | Test-Sets | Tested Capabilities |
|---|---|---|---|
| 1 | Base journey | - Customer: Prepare yourself - Supplier: Prepare yourself - Customer: Create WeekBasedMaterialDemand - Customer: Provide WeekBasedMaterialDemand - Supplier: Consume WeekBasedMaterialDemand - Supplier: Create WeekBasedCapacityGroup - Supplier: Provide WeekBasedCapacityGroup - Customer: Consume WeekBasedCapacityGroup - Customer: Visualize CapacityGroup together with MaterialDemand - Supplier: Visualize CapacityGroup together with MaterialDemand - Customer: Provide IdBasedRequestForUpdate - Supplier: Consume IdBasedRequestForUpdate - Supplier: Provide IdBasedRequestForUpdate - Customer: Consume IdBasedRequestForUpdate - Customer: Create IdBasedComment - Customer: Provide IdBasedComment - Supplier: Consume IdBasedComment - Supplier: Create IdBasedComment - Supplier: Provide IdBasedComment - Customer: Consume IdBasedComment - Customer: Visualize IdBasedComment together with CapacityGroup and MaterialDemand - Supplier: Visualize IdBasedComment together with CapacityGroup and MaterialDemand | - Providing and consuming demand data - Providing and consuming capacity data - Comparing demand and capacity data - Request for update - Comments |
| 2 | Demand volatility metrics journey | - Customer: Prepare yourself - Supplier: Prepare yourself - Customer: Create WeekBasedMaterialDemand - Customer: Provide WeekBasedMaterialDemand - Supplier: Consume WeekBasedMaterialDemand - Supplier: Create WeekBasedCapacityGroup - Supplier: Provide WeekBasedCapacityGroup - Customer: Consume WeekBasedCapacityGroup - Customer: Visualize CapacityGroup together with MaterialDemand - Supplier: Visualize CapacityGroup together with MaterialDemand | - Providing and consuming demand data - Providing and consuming capacity data - Comparing demand and capacity data - Demand volatility metrics |
| 3 | Simulated delta production journey | - Customer: Prepare yourself - Supplier: Prepare yourself - Customer: Create WeekBasedMaterialDemand - Customer: Provide WeekBasedMaterialDemand - Supplier: Consume WeekBasedMaterialDemand - Supplier: Create WeekBasedCapacityGroup - Supplier: Provide WeekBasedCapacityGroup - Customer: Consume WeekBasedCapacityGroup - Customer: Visualize CapacityGroup together with MaterialDemand - Supplier: Visualize CapacityGroup together with MaterialDemand | - Providing and consuming demand data - Providing and consuming capacity data - Comparing demand and capacity data - Simulated delta production |
| 4 | Load factors journey | - Customer: Prepare yourself - Supplier: Prepare yourself - Customer: Create WeekBasedMaterialDemand - Customer: Provide WeekBasedMaterialDemand - Supplier: Consume WeekBasedMaterialDemand - Supplier: Create WeekBasedCapacityGroup - Supplier: Provide WeekBasedCapacityGroup - Customer: Consume WeekBasedCapacityGroup - Customer: Visualize CapacityGroup together with MaterialDemand - Supplier: Visualize CapacityGroup together with MaterialDemand | - Providing and consuming demand data - Providing and consuming capacity data - Comparing demand and capacity data - Load factors |
Base Journey
Notice
This work is licensed under the CC-BY-4.0
- SPDX-License-Identifier: CC-BY-4.0
- SPDX-FileCopyrightText: 2023 BASF SE
- SPDX-FileCopyrightText: 2023 Bayerische Motoren Werke Aktiengesellschaft (BMW AG)
- SPDX-FileCopyrightText: 2024 CatX Service GmbH
- SPDX-FileCopyrightText: 2023 Fraunhofer-Gesellschaft zur Förderung der angewandten Forschung e.V (Fraunhofer)
- SPDX-FileCopyrightText: 2023 Henkel AG & Co.KGaA
- SPDX-FileCopyrightText: 2023 Mercedes Benz Group AG
- SPDX-FileCopyrightText: 2023 SAP SE
- SPDX-FileCopyrightText: 2023 SupplyOn AG
- SPDX-FileCopyrightText: 2023 Volkswagen AG
- SPDX-FileCopyrightText: 2023 ZF Friedrichshafen AG
- SPDX-FileCopyrightText: 2023 Contributors to the Eclipse Foundation